feat(Async): RunSynchronouslyImmediate by bartelink · Pull Request #19804 · dotnet/fsharp

bartelink · 2026-05-25T17:55:27Z

Implements RunSynchronouslyImmediate per fsharp/fslang-suggestions#1042

Checklist

Needs a killer example of the stacktrace difference between Async.RS vs Async.RSI
- One aspect should potentially be represented as a regression test
- More importantly, if the xmldoc summary can shout out the difference / why one should consider deadlocking, that's key
Test cases added
- validate absence of thread hops
- characterize stacktrace that can be expected (perhaps contrasting with RunSynchronously)
Release notes entry updated:

github-actions · 2026-05-25T17:56:11Z

❗ Release notes required

✅ Found changes and release notes in following paths:

Change path Release notes path Description

src/FSharp.Core docs/release-notes/.FSharp.Core/11.0.100.md

Copilot

Pull request overview

Adds Async.RunSynchronouslyImmediate to FSharp.Core to allow running an Async<'T> synchronously while always executing the initial step on the calling thread (aimed at improved diagnostics/stack traces in FSI/tests), with accompanying API surface updates, documentation, unit tests, and release notes.

Changes:

Add public API Async.RunSynchronouslyImmediate and wire it through Async primitives.
Add unit tests characterizing basic behavior and key differences vs Async.RunSynchronously.
Update FSharp.Core surface area baselines and release notes; extend XML docs for RunSynchronously/RunSynchronouslyImmediate.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModule.fs	Adds unit tests for `RunSynchronouslyImmediate` and contrasts with `RunSynchronously`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.release.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.debug.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.release.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.debug.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
src/FSharp.Core/async.fsi	Adds XML docs for the new API and revises `RunSynchronously` docs to reference it.
src/FSharp.Core/async.fs	Implements the new API by exposing an “immediate” synchronous runner and refactoring `RunSynchronously` internals.
docs/release-notes/.FSharp.Core/11.0.100.md	Adds release note entry for `Async.RunSynchronouslyImmediate`.

Comments suppressed due to low confidence (1)

tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModule.fs:527

This test uses a raw Thread but doesn’t capture exceptions from the thread body. Any unexpected exception inside the thread (including from Async.RunSynchronously) will be unhandled and may crash the test process rather than reporting a normal xUnit failure. Capture exceptions in the thread and rethrow/assert after Join.

        let t = Thread(fun () ->
            callerThreadId <- Thread.CurrentThread.ManagedThreadId
            async { runSyncThreadId <- Thread.CurrentThread.ManagedThreadId }
            |> Async.RunSynchronously
            async { immThreadId <- Thread.CurrentThread.ManagedThreadId }
            |> Async.RunSynchronouslyImmediate)

T-Gro · 2026-05-26T11:22:05Z

+        /// <summary><p>Runs the asynchronous computation, starting and blocking on the
+        /// calling thread regardless of <see cref="P:System.Threading.SynchronizationContext.Current"/> being non-
+        /// <c>null</c> or <see cref="P:System.Threading.Thread.IsThreadPoolThread"/> being <c>false</c>.</p>
+        /// <p>Any exception raised by the computation is propagated to the caller, with a stack trace bearing
+        /// caller frames for exceptions raised before the first asynchronous suspension.</p>
+        /// <p>Warning: may cause deadlock if called on a UI thread.</p>
+        /// </summary>
        ///
-        /// The timeout parameter is given in milliseconds.  A value of -1 is equivalent to
-        /// <see cref="F:System.Threading.Timeout.Infinite"/>.
+        /// <remarks>
+        /// <p>Warning: this method hard-blocks the calling thread for the duration of the computation,
+        /// including threads that have a non-<c>null</c>
+        /// <see cref="P:System.Threading.SynchronizationContext.Current"/> such as UI threads. Calling it
+        /// from a UI thread will make the UI unresponsive and risks deadlock if any continuation in the
+        /// computation needs to be dispatched back to that context.
+        /// </p>


Summary and remarks feel very much like.

Maybe summary = launches on the calling thread and what it is good for
remarks - the exact conditions and risks

?

@T-Gro see #19804 (comment) - I'll rewrite the xmldoc based on what we decide. I agree that there should be less/no duplication, and summary should mention only risk (deadlock), especially if only key reason to use new fn is to get a direct callstack in a debugger.

T-Gro · 2026-05-26T11:24:09Z

        /// </code>
-        /// Prints "A", "B" immediately, then "C", "D" in 1 second. result is set to 17.
+        /// Prints <c>"A"</c>, <c>"B"</c> immediately (on the calling thread),
+        /// then (from a continuation thread), after about one second, <c>"C"</c>,


Isn't the example commentary ((from a continuation thread)) swapped between the two versions?

I'll double check after the rewrite when my comment in main thread is resolved - lots of cut and paste going on. Assuming the key diff is deemed to be less noise in the stack trace, the examples will emphasize that the first block prior to suspension runs on calling thread vs a threadpool thread

bartelink · 2026-05-26T11:28:21Z

@T-Gro I've implemented as per OP of fsharp/fslang-suggestions#1042

Firstly, in a debugger context a first chance exception breakpoint has more direct causation vs having to disentangle an adjacent thread waiting, which tooling may or may not be able to convey unaided.

However, while the exception stack trace has less noise, it's not significantly better AFAICT:

It seems the TL;DR value prop is:

in a debugger breakpoint there's an obvious call stack
stack traces have 2/3 less noise layers
default perf is better as no egregious thread hops (though for many real world cases, there may be a root RunSynchronously that pays the hop price and then nested calls don't pay?)

But its not a slam dunk as:

potential deadlocks
confusion about a longstanding thing that people's fingers and thousands of tutorials had

This is making me think I should dial back the xmldoc from where I have it trying to set a "use the new RunSynchronouslyImmediate in FSI from now on" vibe (as I've tried to do with AwaitTask vs Await where it is a slam dunk)

cc @majocha @dsyme

bartelink · 2026-05-26T11:43:50Z

        |> unfake

+    [<DebuggerHidden>]
+    let RunSynchronouslyImmediate2 computation (cancellationToken: CancellationToken) =


@T-Gro If I put this body (which gives a shorter callstack than the original RunSynchronouslyImmediate impl at L1141) into RunSynchronouslyImmediate, the tests also pass but I guess there is more risk of regressions due to changing a very hot path.

Let me know if you'd prefer for RunSynchronouslyImmediate2 and RunSynchronouslyImmediate to live on side by side as the code is now, or whether you're ok with me collapsing the two into this impl

github-project-automation Bot added this to F# Compiler and Tooling May 25, 2026

github-project-automation Bot moved this to New in F# Compiler and Tooling May 25, 2026

feat(Async): RunSynchronouslyImmediate

41f5f13

bartelink force-pushed the run-synchronously-immediate branch from 181ce94 to 41f5f13 Compare May 25, 2026 18:44

Doc polish / characterization tests

69e41a2

bartelink force-pushed the run-synchronously-immediate branch from d6a0470 to 69e41a2 Compare May 25, 2026 22:07

bartelink marked this pull request as ready for review May 25, 2026 22:19

bartelink requested a review from a team as a code owner May 25, 2026 22:19

Copilot AI review requested due to automatic review settings May 25, 2026 22:19

Copilot started reviewing on behalf of bartelink May 25, 2026 22:19 View session

Copilot AI reviewed May 25, 2026

View reviewed changes

Comment thread tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModule.fs Outdated

Comment thread src/FSharp.Core/async.fsi Outdated

Comment thread src/FSharp.Core/async.fsi Outdated

Comment thread src/FSharp.Core/async.fsi Outdated

github-actions Bot added the AI-Tooling-Check-Scanned-Clean Tooling check: diff analyzed, no interesting infrastructure files label May 25, 2026

bartelink added 2 commits May 26, 2026 11:03

copilot Code review changes

19e3482

RunSynchronouslyImmediate2

cc7fe0b

T-Gro reviewed May 26, 2026

View reviewed changes

bartelink mentioned this pull request May 26, 2026

Add Async.RunImmediate fsharp/fslang-suggestions#1042

Open

5 tasks

bartelink commented May 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(Async): RunSynchronouslyImmediate#19804

feat(Async): RunSynchronouslyImmediate#19804
bartelink wants to merge 4 commits into
dotnet:mainfrom
bartelink:run-synchronously-immediate

bartelink commented May 25, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

T-Gro May 26, 2026

Uh oh!

bartelink May 26, 2026

Uh oh!

T-Gro May 26, 2026

Uh oh!

bartelink May 26, 2026 •

edited

Loading

Uh oh!

bartelink commented May 26, 2026

Uh oh!

bartelink May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

bartelink commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

github-actions Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❗ Release notes required

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

T-Gro May 26, 2026

Choose a reason for hiding this comment

Uh oh!

bartelink May 26, 2026

Choose a reason for hiding this comment

Uh oh!

T-Gro May 26, 2026

Choose a reason for hiding this comment

Uh oh!

bartelink May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink commented May 26, 2026

Uh oh!

bartelink May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bartelink commented May 25, 2026 •

edited

Loading

github-actions Bot commented May 25, 2026 •

edited

Loading

bartelink May 26, 2026 •

edited

Loading